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1.0 INTRODUCTION 



This document describes the message conventions which will be used 
when defining messages for the CDCNET external interface. These 
conventions will apply to all command responses and unsolicited 
alarm messages. 

Every input by the network operator should consistently produce some 
perceptible response output from the network. Messages comprise 
prompts, status messages (to indicate system state, acknowledge 
executed commands, etc.), error messages, .warning messages, "helps" 
and tutorials. The guidelines given in this document are provided 
to assist in the creation of appropriate messages. Also command 
response and alarm message headers to be used within CDCNET are 
documented. 



1.1 REFERENCES 

Software Design Guide (CDC-PUB 1501 1400) July 84 

Error Message Guidelines - R. K. Foster 

DI Hardware GDS (ARH4948) - F. Holland 

CDCNET Network ERS (ARH6226) - ACSD System Design 

CYBER 180 System Interface Standard (S2196) 
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Error messages represent a very important, though often neglected, 
interface between the software and user. Proper attention to 
producing polite, correct, and clear error messages can do a lot 
toward improving the overall usability of the system. The following 
conventions should be used in defining error message text: 

- Write from the user/operators point of view. Avoid the vague 
"SYNTAX ERROR" or obscure internal codes. Use variable names and 
concepts known to the operator. Avoid computer -jargon. 

- Message must be written in English. Messages should follow normal 
rules for English grammer and punctuation, although "pidgin English" 

- the omission of selected subjects, verbs and objects in the 
interest of brevity where the meaning is clear ~ is acceptable. 

Messages should be polite and courteous. Words such as "illegal" 
or "invalid" should be avoided in favor of words like "incorrect" or 
"unknown". Error Messages should, where appropriate, suggest what 
the user/operator ought to do to correct the error. For example 

The line number must be an integer. 

NOT 

Illegal line number. 

- Messages must be formattable for 80 character displays. Telegraph 
style is much better than long-winded prose. However, the message 
must be descriptive of the error. Messages like "Bad Arguement" 
don't say enough. 

- Consistent terminology is extremely important. Internal names and 
terms the user/operator may not be familiar with should not be 
included in the message. 

- Names used in a command response should be the same as the 
parameter names. For example: 

IF the command is: 

send_coramand system~columbia command*' display_date_and_time' 

THEN for example the response should be: 

Command could not be delivered to system COLUMBIA. 
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- Identification must be provided with variable information. For 
example: 

File FRED not found in catalog SALLY. 
Variable VAR1 must be scalar. 

NOT 

FRED not found. 
VARl must be scalar. 

- Use ending punctuation. It indicates to the user/operator that 
the message is not continued on the next" line and adds to the 
readability of the message. 

- Messages should be oriented toward an inexperienced or casual 
user/operator such that the message can be understood and 
appropriately responded to without a reference to a manual. 

- A single message should diagnose a single error. For example, if 
the meaning of a message is "more than seven characters or leading 
non-alphabetic character or null identifier" it should be three 
messages. Usually, the code must make three separate tests, so it 
is easy to be precise. 

- Abbreviations should be avoided. Whenever possible limit the 
characters used to alphanumeric plus English punctuation. Avoid use 
of characters that appear differently on different devices. 

- Acronyms may be used only if they are meaningful to the 
user/operator. Section 6.0 has a list of allowed acronyms for the 
CDCNET product. The use of any acronyms other than those listed in 
section 6.0 must be approved through the CDCNET review board 
discussed in section 7.0 . 

- Words beginning with "multi" and "non" are not hyphenated. Don't 
use "(s)" to indicate an optional plural usage; either singular or 
plural is acceptable. 

Error messages should use upper and lower case as they are 
normally used in the English language. Upper case should be used to 
distinguish "computer" words from normal English words. For 
example: 

File FRED not found. 

Specify keyword NEW. 

- Place the information that must be remembered the longest near the 
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beginning of the message. 

- Place information that is most difficult near the beginning and 
least difficult near the end. 

- Messages should be affirmative, brief, simple, and employ the 
active voice; e.g., "To send the message press ENTER." rather than 
"The message is sent by pressing ENTER.". 

- Messages should read in the temporal sequence of events; e.g., 
"Complete entry before pressing ENTER." not "Press ENTER after 
completing entry." 

- Messages which convey simi liar information should be consistent, 
For example: 

Command PURG not found in SSYSTEM. 

File FRED not found in SALLY. 

Job AABCS not found in input queue. 

- Messages which indicate that an item must be a member of a set v 
should list the acceptable choices. For example: 

Parameter KIND must be INTEGER, BOOLEAN, or STRING. 

or 

SCOPE parameter for CREATE_VARIABLE command must be LOCAL, 
XDCL, XREF, or JOB. 

For sets longer than approximately seven items, the list should not 
be given. Use: 

IST3 is not a correct selection for TERMINAL_CLASS parameter. 

- When a value is outside of a range, list the range: 

Value for YEAR must be between 1899 and 2201. 

- Error messages should not be issued for trivial, correctable 
errors - nor should they be errors. For example, errors such as 
missing or redundant terminators should not be errors at all. If a 
reasonable assumption can be made as to the intent of an input, it 
should be acted upon as though it were "valid". No error message 
should be produced for these cases. If it is not perfectly clear 

what assumption was made, the assumption was probably not reasonable / 

to begin with. 
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- Output bases should be displayed on messages for numeric values. 
Radixes will be shown in parenthesis. No radix displayed will 
indicate base 10. 

- As little ASCII data (i.e., data type character octet) as possible 
should be generated as the variable data. Operator entered ASCII or 
strings that were configurable options are allowed. No fixed 
strings. For. example, the Device Interface system name can be sent 
as part of the variable data since the system name is a configurable 
option (i.e., it is assigned by an operator command at configuration 
time) . 

- Whereever possible share message templates across different 
software components. There are common message templates which are 
intended to be used across the CDCNET product. When defining 
message templates always attempt to use existing templates. 

- Within a software component share templates across alarms/logs and 
command responses (e.g., don't use the terminology UP and DOWN in a 
command response, and then use ON and OFF in an alarm message 
generated by the same component). Use consist terminology in a 
given software component and also in related components. For 
example all lower layer software should use the same terminology for 
a networks status (e.g., UP, DOWN, CNFG, DEGRADED, etc.). 

- Keep displays to less than or equal to 24 lines for a single 
template. 

- Alarms and Responses must be descriptive (i.e., template 
definitions should contain descriptive ASCII text describing the 
error). For example: 

CDCNET ALARM ****** 

system_name 83/08/04 11.00.35 30432 

— ERROR — Incorrectly formatted Routing Information Data Unit 

Routing Information Data Unit * f f edc!2450cdcdl20123ccf 



NOT 



CDCNET ALARM ****** 

system_name 83/08/04 11.00.35 432 

—ERROR— error - bad RIDU 

error code ■ 3 

ridu - 1234567890abcdef0123456 
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- A command response message id will be displayed with every 
response. The response message id uniquely identifies the 
condition. 

- A log message id will be displayed with every alarm and log 
message. The message id uniquely identifies the condition. Also 
alarm and log message ids are distinct from command response message 
ids such that every condition within the CDCNET system has a system 
unique identifier. 

- Every CDCNET command processor will generate a displayable 
response. No command processors should send just a success 
condition code with no actual response. For example: 

A successful enable_line command should result in the response "line 
xxx enabled" or "lines enabled" not just a success condition code. 

- Logical Names and Physical Names will be used to represent 
physical elements. Physical names will be the default provided 
names. For example: 

Port number 1 on LIM 2 will have a physical name of $LIM2_P0RT1. A 
logical name may be JACKS_TERMINAL_PORT. 

Exact conventions on how physical names are formed for elements is 
given in section 5.0 . 
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4.0 CDCNET MESSAGE HEADERS 



4.1 COMMAND RESPONSE HEADER 



This section defines the message header for a CDCNET command 
response. 

<system name> <date> <time> <response message id> 
— <severity level> — <condition description> 



system name: The system name is the name of the system 
where the response was generated from. The system 
name can be up to 31 characters in length. 

date: Date in the form of YY/MM/DD 

time: Time in the form of HH.MM.SS 

response message id: The response message id uniquely 
identifies this condition (i.e., response) within 
the system. 

severity level: The severity level of the condition. 
Possible values are INFORMATIVE, WARNING, ERROR, 
FATAL, and CATASTROPHIC. 

condition description text: Specifies the condition. 
This field should distinctly and descriptively 
specify the existing condition. 

Example command response with header: 

system_name 83/08/04 11.00.35 1033 

— WARNING — Command could not be delivered to system arh_101 

4.2 ALARM HEADER 



This section defines the message header for a CDCNET alarm message. 

CDCNET ALARM ****** 

<system name> <date> <time> <log message id> 

— <severity level> — <condition description> 
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system name: The system name is the name of the system 
where the alarm message was generated from. The 
system name can be up to 31 characters in length. 

date: Date in the form of YY/MM/DD 

time: Time in the form of HH.MM.SS 

log message id: The log message id uniquely identifies 
this condition (i.e., log message) within the 
system. Log message ids are also distinct from 
response message ids such that every condition 
within the system has a unique condition code. 

severity level: The severity level of the condition. 
Possible values are INFORMATIVE, WARNING, ERROR, 
FATAL, and CATASTROPHIC. 

condition description text: Specifies the condition. 
This field should distinctly and descriptively 
specify the existing condition. 



Example alarm message with header: 

CDCNET ALARM ****** 

system_name 83/08/04 11.00.35 30432 

— ERROR — Incorrectly formatted Routing Information Data Unit received 

Routing Information Data Unit ■= ffedcl2450cdcdl20123ccf 
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5.0 CONVENTIONS FOR FORMING PHYSICAL NAMES 



Physical names are the names provided hy CDC to address a physical 
component within the DI. Examples are names to address circuit 
cards such as CIMs, LIMs, MPB, SMMs, etc. and physical names to 
address terminal lines and network solutions. Physical names will 
always be provided for the DI components but does not preclude 
network operations from configuring the DI components with logical 
names. The logical names are defined via the CDCNET network 
configuration commands. The logical name when defined is in place 
of not in addition to the physical name. 

The physical name for a component is based on the physical location 
of the component within the DI and based on the circuit card type. 
The following conventions will be used to form the DI physical 
names : 

- $MPB0 .. $MPBn where n (0 to 7) is the card slot position. For 
example if an MPB card was located in card slot 2 of the DI, the 
physical name for that MPB card would be '$MPB2'. 

- $PMM0 .. $PMMn where n is the card slot position. 

- $SMM0 .. $SMMn where n is the card slot position. 

- $CIM0 .. $CIMn where n is the card slot position. 

- $PIM0 .. $PIMn where n is the card slot position. 

- $MCI0 .. $MCIn where n is the card slot position. 

- $ESCX0 .. $ESCIn where n is the card slot position. 

- $LIM0 . . $LIMn where n is the lira card slot position. 

- $LIMn_PORTm where n is the lim card slot position and m is the 
port number (0 to 3) from top to bottom. Top being physically the 
upper-most port on the LIM card when the card is inserted in the 
Device Interface. 

- Wild card characters can be applied to these names just as they 
are applied to other DI titles/names. For example: 

$LIM* means all LIMs (i.e., matches on all names which 
begin with '$LIM') 

$SMM* means all SMMs (i.e., matches on all names which 
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begin with '$SMM') 

SLIM2* means LIM 2 as well as all ports on LIM 2 (i.e., 
matches on all names which begin with ' $LIM2') 

$LIM?_P0RT2 means port 2 on all LIMs (i.e., matches on 
$LIM0_PORT2, $LIM1_P0RT2, SLIM2_P0RT2, $LIM3_PORT2, etc.) 

SLIM[3..4]_PORT3 means port 3 on LIM 3 and LIM A (i.e., 
matches on $LIM3_PORT3 and $LIM4_PORT3) 

ETC. 

For more details on wild card character support refer to the 
Network Operations section of the CDCNET Network ERS. 

The above conventions are best described through an illustrated 
example. Below is an example DI configuration and the 
physical names provided. 
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The following physical names will exist for the above configuration: 

$MPB0, $PMM1, $SMM2, $SMM3, $MCI5, SCIM6, SESCI7, $LIM0, $LIM1, 
$LIM2, $LIM3, $LIMA, $LIM5, $LIM6, $LIM7, $LIM0_PORT0 to 
$LIM0_PORT3, $LIM1 PORTO to $LIMl_P0RT3, $LIM2_PORT0 to $LIM2_P0RT3, 
$LIM3_P0RT0 to $LIM3_PORT3, $LIM4 PORTO to $LIM4_PORT3, $LIM5_PORT0 
to $LIM5 P0RT3, $LIM6 PORTO to $LIM6 P0RT3, and $LIM7 PORTO to 
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SLIM7_PORT3 . 

These names are maintained appropriately through the associated 
configuration commands which are used to configure the different 
components. For more details on the DI layout and hardware 
components refer to the DI Hardware GDS (ARH4948) . 

In the above DI configuration, if the following command were 
entered: 

display_hardware_status device_name"*$LIM* 

the response would contain the hardware status for all LIMs (LIMs 
to 7) including the status of each port. 
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ACRONYMS 

CDCNET 

MDI 

NDI 

TDI 

MTI 

URI 

DNC 

RCI 

MPB 

SMM 

PMM 

PIM 

CIM 

ESCI 

LIM 

MCI 

TIP 

IVT 

RS232 

RS449 

HDLC 

SSR 



DESCRIPTION 

Control data Distributed Communications NETwork 

Mainframe Device Interface 

Network Device Interface 

Terminal Device Interface 

Mainframe Terminal Interface 

Unit Record Interface 

Data Network Concentrator 

Remote Concentrator Interface 

Master Processor Board 

System Main Memory 

Private Main Memory 

Parallel Interface Module 

Communications Interface Module 

Ethernet Serial Channel Interface 

Line Interface Module 

Mainframe Channel Interface 

Terminal Interface Program 

Interactive Virtual Terminal 

EIA Recommended Standard (port type) 

EIA Recommended Standard (port type) 

High level Data Link Control 

Stream Service Routine 
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X.25 



TELENET 



TYMNET 

DATAPAC 
TRANSPAC 



CCITT recommendation that specifies the interface 

between user data terminal equipment (DTE) and 

packet-switching data circuit-terminating 
equipment (DCE) . 

Communications carrier network. A public, 

intelligent packet-switched network connecting 

subscriber terminals and computers. Based on 
X.25 . 

Communications carrier network. A network 
similar to TELENET but based on minicomputer 
switching. Based on X.25 . 

Canadian communications carrier network 

French communications carrier network 
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7.0 REVIEW PROCESS 



The entire CDCNET message set will be periodically reviewed by a 
review board. Each message will be evaluated using the guidelines. 
Where possible improved messages will be proposed. 

All response messages to an operator or user should be documented in 
the External Reference Specification. This includes log message 
documentation and command documentation. The documenting of command 
responses is as important as the documentation of the command 
itself. The responses generated will be evaluated by the Advanced 
Communication Systems Development (ACSD) Technical Design Review 
Board (TDRB) for adherence to the guidelines set forth in this 
document. 
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Appendix B - Planned Enhancements and Corrections 

The following enhancements are planned for these conventions: 

Addition of specific conventions for the format of specific 
messages (e.g., logs/alarms for invalid PDU's, unexpected 
disconnects etc.) that are common across multiple components 
in DCNS software. These conventions will form the contents of 
Appendix A. to this document. 
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